# ESP32 产品线

```{admonition} 本文引用的文件
:class: note

- `docs/README.md`
- `firmware/README.md`
- `esp32s3/firmware/README.md`
- `firmware/port/Makefile`
- `firmware/port/boards/mpython/mpconfigboard.h`
- `firmware/port/boards/mpython-classroom-kit/mpconfigboard.h`
- `firmware/port/boards/labplus-experiment-box-2024/mpconfigboard.h`
- `esp32s3/firmware/boards/mpython_v3/mpconfigboard.h`
- `esp32s3/firmware/main/Kconfig.projbuild`
- `esp32s3/firmware/components/gen_bmgr_codes/board_manager.defaults`
- [docs/docs/zh_CN/board/introduction.rst](../../../products/mpython/board/introduction.rst)
```

## 产品概述
本项目为 ESP32 掌控板产品线的知识基座，覆盖标准掌控板、课堂套件、实验箱等板型，以及其对应的固件与文档体系。ESP32 版本基于 MicroPython + ESP-IDF v3.3.2/v4.0.1 + Makefile 构建；ESP32-S3 版本基于 ESP-IDF v5.x + MicroPython + CMake 构建，并新增 LVGL、AI 视觉等能力。文档源位于 docs/（Sphinx + reStructuredText），固件源位于 firmware/（ESP32）与 esp32s3/firmware/（ESP32-S3）。

- 目标用户：K12 教师与学生、创客开发者、教育设备集成商
- 核心价值：以 Python 降低入门门槛，提供从图形化到代码的平滑学习路径；通过多板型覆盖教学、竞赛、实验场景
- 适用场景：课堂编程、项目式学习、物联网原型开发、AI 语音/视觉体验

**章节来源**
- `docs/README.md:1-16`
- `firmware/README.md:1-57`
- `esp32s3/firmware/README.md:1-242`
- [docs/docs/zh_CN/board/introduction.rst:1-18](../../../products/mpython/board/introduction.rst)

## 核心业务流程
围绕“选择板型 → 配置构建环境 → 编译固件 → 烧录运行”的主流程，结合不同板型的差异化配置，形成统一的可复用构建链路。

```text
flowchart TD
A["开始"] --> B{"选择板型"}
B --> |ESP32| C["设置 ESPIDF 环境变量<br/>指向 v3.3.2 或 v4.0.1"]
B --> |ESP32-S3| D["安装 ESP-IDF v5.x<br/>准备 CMake 工具链"]
C --> E["指定 BOARD=mpython / classroom-kit / experiment-box"]
D --> F["通过 Kconfig 选择 mpython_v3 / Ledong_v2 等"]
E --> G["执行 make submodules && make"]
F --> H["执行 idf.py build / make 构建"]
G --> I["生成 bootloader.bin / partitions.bin / application.bin"]
H --> I
I --> J["使用 esptool 或 idf.py flash 烧录"]
J --> K["上电运行 REPL 与示例程序"]
```

**图示来源**
- `firmware/port/Makefile:1-52`
- `esp32s3/firmware/README.md:77-143`

**章节来源**
- `firmware/port/Makefile:1-52`
- `esp32s3/firmware/README.md:77-143`

## 功能模块清单
本仓库按“文档 + 固件 + 板型配置”组织，形成面向教学与开发的完整能力矩阵。

- 文档层（docs/）
  - 中文文档（docs/docs/zh_CN/）：板卡介绍、驱动、库参考、教程、项目指南、FAQ
  - 示例代码（docs/examples/）：display/button/audio/ble/IoT/game 等分类，便于快速上手
- 固件层（firmware/port/）
  - builtins/：C 级模块（machine/motion/music/radio/network 等）
  - modules/：Python 级模块（bluebit/gui/neopixel/urequests 等）
  - drivers/：C 硬件驱动（codec/mpu6050/rfid/rgbLED5x5）
  - file_system/：扩展库（siot/yeelight/xunfei/smartcamera 等）
- 板型配置（firmware/port/boards/）
  - mpython（标准掌控板）
  - mpython-classroom-kit（课堂套件）
  - labplus_classroom_kit_II（课堂套件 II）
  - labplus_1956
  - labplus-experiment-box-2024（实验箱）
  - GENERIC（通用）
- ESP32-S3 固件层（esp32s3/firmware/）
  - 新增 usercmodule（LVGL 绑定、ESP-Who AI 视觉）
  - 新增 components（esp_lcd_jd9853 屏幕驱动、gen_bmgr_codes）
  - 新增 modules（ai_cloud、ATGM336H_5N、max30102、CSK6011A、xgo 等）
- ESP32-S3 板型配置（esp32s3/firmware/boards/）
  - mpython_v3（标准 S3 掌控板）
  - labplus_Ledong_v2（乐动掌控 2.0）
  - labplus_for_xuejing（学境版）
  - labplus_xunfei_js_primary / middle（讯飞 JS 初级/中级版）

**章节来源**
- `docs/README.md:1-16`
- `firmware/README.md:1-57`
- `esp32s3/firmware/README.md:1-242`

## 数据与状态
- 板型标识与 MCU 名称
  - ESP32 板型在 mpconfigboard.h 中定义 MICROPY_HW_BOARD_NAME 与 MICROPY_HW_MCU_NAME
  - ESP32-S3 板型同样在 mpconfigboard.h 中声明，并通过 Kconfig 选择具体板型
- 构建产物状态
  - ESP32：make 生成 bootloader.bin、partitions.bin、application.bin，最终打包为 firmware.bin
  - ESP32-S3：idf.py/build 生成对应分区与应用镜像，支持 OTA/SPIRAM 等变体
- 运行时状态
  - 通过 REPL（UART/USB）进行交互调试
  - WiFi/BLE 连接状态由网络模块管理
  - 传感器与外设状态由各自驱动维护（如 motion、audio、framebuf）

```text
classDiagram
class BoardConfig {
+string board_name
+string mcu_name
+bool adc_enabled
+bool dac_enabled
}
class BuildSystem {
+string toolchain
+string idf_version
+string target_board
+generate_bin()
}
class Runtime {
+repl()
+wifi_state()
+peripheral_status()
}
BoardConfig --> BuildSystem : "决定编译选项"
BuildSystem --> Runtime : "生成可执行镜像"
```

**图示来源**
- `firmware/port/boards/mpython/mpconfigboard.h:1-22`
- `firmware/port/boards/mpython-classroom-kit/mpconfigboard.h:1-26`
- `firmware/port/boards/labplus-experiment-box-2024/mpconfigboard.h:1-21`
- `esp32s3/firmware/boards/mpython_v3/mpconfigboard.h:1-29`
- `esp32s3/firmware/main/Kconfig.projbuild:1-32`

**章节来源**
- `firmware/port/boards/mpython/mpconfigboard.h:1-22`
- `firmware/port/boards/mpython-classroom-kit/mpconfigboard.h:1-26`
- `firmware/port/boards/labplus-experiment-box-2024/mpconfigboard.h:1-21`
- `esp32s3/firmware/boards/mpython_v3/mpconfigboard.h:1-29`
- `esp32s3/firmware/main/Kconfig.projbuild:1-32`

## 关键约束与边界
- 构建环境与依赖
  - ESP32：要求 ESP-IDF v3.3.2 或 v4.0.1（通过 git hash 校验），pyparsing < 2.4；需 xtensa-esp32-elf 工具链
  - ESP32-S3：要求 ESP-IDF v5.x（如 v5.0.4），CMake 工具链；支持 OTA、SPIRAM 等变体
- 板型差异边界
  - ESP32 板型通过 mpconfigboard.h 启用/禁用 ADC/DAC、内置模块（motion、rgbLED5x5）
  - ESP32-S3 板型通过 Kconfig 选择具体板型，并在 mpconfigboard.h 中启用音频、RFID、I2C 等新特性
- 运行时边界
  - 网络：WiFi/BLE 需在系统初始化后配置；部分板型需切换天线
  - 存储：NVS 用于持久化配置；文件系统支持 FAT/LFS2
  - 显示：ESP32 使用 OLED（SSD1106），ESP32-S3 使用 TFT LCD（st7789）
- 许可与开源协议
  - 软件 GPL-3，硬件 CERN，文档 CC0；OSHWA 认证开源硬件

**章节来源**
- `firmware/port/Makefile:65-118`
- `esp32s3/firmware/README.md:22-75`
- `firmware/port/boards/mpython-classroom-kit/mpconfigboard.h:1-26`
- `esp32s3/firmware/boards/mpython_v3/mpconfigboard.h:1-29`
- `esp32s3/firmware/main/Kconfig.projbuild:1-32`
- `firmware/README.md:44-57`